home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / BASIC / LIB / EVENTSHELL / DOCS / Draw < prev    next >
Text File  |  1996-04-19  |  14KB  |  554 lines
  1.  
  2. Draw units
  3. The units used by the DrawLib routines can
  4. be specified in several different units.
  5. Choosing units can be achieved with the
  6. following calls :
  7.  
  8. PROCshell_DrawSetUnitsMM millimeters
  9. PROCshell_DrawSetUnitsCM centimeters
  10. PROCshell_DrawSetUnitsIN inches
  11. PROCshell_DrawSetUnitsOS OS units
  12. PROCshell_DrawSetUnitsPT points
  13.  
  14. Drawfiles are created in millimeters by
  15. default.
  16.  
  17. --------------------------------------------------------
  18.  
  19. PROCshell_DrawCreateFile
  20. =>    int    address of drawfile buffer
  21.          (contents ignored on entry)
  22.  
  23. <=    address of drawfile buffer is
  24.     updated
  25.  
  26. The drawfile is created in a RAM buffer,
  27. the address of which is returned by the
  28. routine. As objects are added to the file
  29. the address of the buffer may change.
  30.  
  31. At any time the buffer contains a valid
  32. drawfile that can be displayed with
  33. PROCshell_DrawRenderFile.
  34.  
  35. Multiple drawfiles can be created at the
  36. same time, adding objects to a particular
  37. drawfile is achieved by specifying the
  38. buffer address.
  39.  
  40. --------------------------------------------------------
  41.  
  42. PROCshell_DrawRenderFile()
  43. =>    int    address of drawfile buffer
  44.     int    x coordinate to render drawfile
  45.          (os units)
  46.     int    y coordinate to render drawfile
  47.          (os units)
  48.     int    address of wimp redraw block
  49.     bool    bounding box flag (TRUE to show object
  50.          bounds, otherwise FALSE)
  51.               
  52. This routine renders (plots) a drawfile which must
  53. be loaded into a buffer using PROCshell_DrawLoadFile,
  54. or created by the user application with
  55. PROCshell_DrawCreateFile.
  56.  
  57. The drawfile is always plotted relative to the current
  58. graphics origin. The scale of the drawfile can be set
  59. using PROCshell_DrawSetScale beforehand. Loading or
  60. creating a new file sets the scale to 1:1.
  61.  
  62. Actual rendering is performed by the DrawFile module
  63. which must be loaded by the application's !Run file.
  64.  
  65. Wimp redraw block
  66.   0  Window handle
  67.   4  Visible area minx (incl)
  68.   8               miny (incl)
  69.  12               maxx (excl)
  70.  16               maxy (excl)
  71.  20  Scrollx
  72.  24  Scrolly
  73.  28  Redraw rect  minx (incl)
  74.  32               miny (incl)
  75.  36               maxx (excl)
  76.  40               maxy (excl)
  77.  
  78. Example Code (DrawRenderFile)
  79. To render a drawfile during a call to a user redraw
  80. function, no bounding boxes shown:
  81.  
  82. DEF FN_UserRedraw_Mainw(blk%,x%,y%)
  83. PROCshell_DrawRenderFile(buffer%,x%+0,y%-1000,
  84. ,blk%,FALSE)
  85. =0
  86. --------------------------------------------------------
  87.  
  88. FNshell_DrawLoadFile()
  89. =>    str    file name
  90.  
  91. <=    int address of drawfile buffer
  92.  
  93. --------------------------------------------------------
  94.  
  95. PROCshell_DrawSaveFile()
  96. =>    int    address of drawfile buffer
  97.     str    file name
  98.  
  99. This routine saves the drawfile and sets
  100. the filetype to &AFF (draw).
  101.  
  102. --------------------------------------------------------
  103.  
  104. FNshell_DrawGetFileSize()
  105. =>    int    address of drawfile buffer
  106.   
  107. <=    int    file size in bytes (excluding
  108.          EvntShell pre-header)
  109.  
  110. --------------------------------------------------------
  111.  
  112. PROCshell_DrawGetBoundingBox()
  113. =>    int    address of drawfile buffer
  114.     int    min x position
  115.     int    min y position
  116.     int    width  
  117.     int    height 
  118.     bool    TRUE if box coords are to be
  119.            returned in OS units, ELSE
  120.            values returned in draw units
  121.  
  122. <=    The x,y,height and width values are
  123.     returned
  124.  
  125. --------------------------------------------------------
  126.  
  127. PROCshell_DrawInitFont()
  128. =>    int    address of drawfile buffer
  129.     str    name of font to initialise
  130.          i.e. 'Trinity.Medium.Italic'
  131.  
  132. <=    address of drawfile buffer is
  133.     updated
  134.  
  135. Before text using outline fonts can be used
  136. in a drawfile it is vital that they are
  137. initialised using this call. Once you have
  138. called this routine for the first time you
  139. must continue initialising all the fonts that
  140. will be needed before creating other objects.
  141.  
  142. It would appear (despite what the PRMs say!)
  143. that font initialisation must occur before any
  144. other objects are defined - that is you must
  145. initialise any fonts directly after creating
  146. the drawfile.
  147.  
  148. Attempting to use fonts that are not available
  149. (has !Fonts been 'seen' by the Filer?) will
  150. cause an error. You should also bear in mind
  151. that using fonts that other people may not have
  152. can cause problems as various applications
  153. react in different ways to this situation.
  154.  
  155. --------------------------------------------------------
  156.  
  157. PROCshell_DrawSetFont()
  158. =>    int    address of drawfile buffer
  159.     str    name of font ("" for System Font)
  160.  
  161. Before this call can be made the font specified must be
  162. initialised with a call to PROCshell_DrawInitFont,
  163. otherwise an error will be generated.
  164.  
  165. All text objects created with PROCshell_DrawOutlineFont
  166. will be in the specified font until the next call to
  167. PROCshell_DrawSetFont.
  168.  
  169. --------------------------------------------------------
  170.  
  171. PROCshell_DrawBox()
  172. =>    int    address of drawfile buffer
  173.     real    x coordinate of bottom left
  174.            of box
  175.     real    y coordinate of bottom left
  176.            of box
  177.     real    width of box
  178.     real    height of box
  179.  
  180. <=    address of drawfile buffer is
  181.     updated
  182.  
  183. The coordinates and dimensions of the box
  184. are given in the currently selected units.
  185.  
  186. --------------------------------------------------------
  187.  
  188. PROCshell_DrawCircle()
  189. =>    int    address of drawfile buffer
  190.     real    x coordinate of centre of
  191.          circle
  192.     real    y coordinate of centre of
  193.          circle
  194.     real    radius of circle
  195.  
  196. <=    address of drawfile buffer is
  197.     updated
  198.  
  199. The coordinates and dimensions of the circle
  200. are given in the currently selected units.
  201.  
  202. --------------------------------------------------------
  203.  
  204. PROCshell_DrawEllipse()
  205. =>
  206.     int    address of drawfile buffer
  207.     real    x coordinate of centre of
  208.            ellipse
  209.     real    y coordinate of centre of
  210.            ellipse
  211.     real    major axis of ellipse
  212.     real    minor axis of ellipse
  213.           
  214. <=    address of drawfile buffer is
  215.     updated
  216.  
  217. The coordinates and dimensions of the ellipse
  218. are given in the currently selected units.
  219.  
  220. --------------------------------------------------------
  221.  
  222. PROCshell_DrawLine()
  223. =>    int    address of drawfile buffer
  224.     real    x coordinate of start of line
  225.     real    y coordinate of start of line
  226.     real    x coordinate of end of line
  227.     real    y coordinate of end of line
  228.           
  229. <=    address of drawfile buffer is
  230.     updated
  231.  
  232. The coordinates and dimensions of the line
  233. are given in the currently selected units.
  234.  
  235. --------------------------------------------------------
  236.  
  237. PROCshell_DrawOutlineFont()
  238. =>    int    address of drawfile buffer
  239.     str    text to insert
  240.     real    width of font  (points)
  241.     real    height of font (points)
  242.     real    x coordinate of bottom left
  243.           of text (current units)
  244.     real    y coordinate of bottom left
  245.           of text (current units)
  246.  
  247. <=    address of drawfile buffer is
  248.     updated
  249.  
  250. Before a text object can inserted the font
  251. used must be initialised with a call to
  252. PROCshell_DrawInitFont, otherwise an error
  253. will be generated. The font to use must also
  254. be selected with PROCshell_DrawSetFont.
  255.  
  256. --------------------------------------------------------
  257.  
  258. PROCshell_DrawSetFillColour()
  259. =>    int    address of drawfile buffer
  260.     int    red    value (0-255)
  261.     int    green    value (0-255)
  262.     int    blue    value (0-255)
  263.  
  264. The colour value is supplied as a 24 bit
  265. value, RISC OS handles the display of the
  266. colour by dithering. 'No colour' may be selected
  267. by specifying the red, green, blue values as
  268. -1, -1, -1.
  269.  
  270. --------------------------------------------------------
  271.  
  272. PROCshell_DrawSetNoFillColour
  273. =>    int    address of drawfile buffer
  274.  
  275. Sets current fill colour back to transparent.
  276.  
  277. --------------------------------------------------------
  278.  
  279. PROCshell_DrawSetPathColour()
  280. =>    int    address of drawfile buffer
  281.     int    red    value (0-255)
  282.     int    green    value (0-255)
  283.     int    blue    value (0-255)
  284.  
  285. The colour value is supplied as a 24 bit
  286. value, RISC OS handles the display of the
  287. colour by dithering. 'No colour' may be selected
  288. by specifying the red, green, blue values as
  289. -1, -1, -1.
  290.  
  291. --------------------------------------------------------
  292.  
  293. PROCshell_DrawSetPathNoColour
  294. =>    int    address of drawfile buffer
  295.  
  296. Sets current path colour back to transparent.
  297.  
  298. --------------------------------------------------------
  299.  
  300. PROCshell_DrawSetPathWidth()
  301. =>    int    address of drawfile buffer
  302.     real    path width (current units)
  303.  
  304. --------------------------------------------------------
  305.  
  306. PROCshell_DrawSetUnitsCM()
  307. =>    int    address of drawfile buffer
  308.  
  309. Sets centimeters to be the current unit of
  310. measurement for the other library routines.
  311.  
  312. --------------------------------------------------------
  313.  
  314. PROCshell_DrawSetUnitsIN()
  315. =>    int    address of drawfile buffer
  316.  
  317. Sets inches to be the current unit of
  318. measurement for the other library routines.
  319.  
  320. --------------------------------------------------------
  321.  
  322. PROCshell_DrawSetUnitsMM()
  323. =>    int    address of drawfile buffer
  324.  
  325. Sets millimeters to be the current unit of
  326. measurement for the other library routines.
  327.  
  328. --------------------------------------------------------
  329.  
  330. PROCshell_DrawSetUnitsOS()
  331. =>    int address of drawfile buffer
  332.  
  333. Sets OS units to be the current unit of
  334. measurement for the other library routines.
  335.  
  336. --------------------------------------------------------
  337.  
  338. PROCshell_DrawSetUnitsPT()
  339. =>    int    address of drawfile buffer
  340.  
  341. Sets points to be the current unit of
  342. measurement for the other library routines.
  343.  
  344. --------------------------------------------------------
  345.  
  346. PROCshell_DrawSetStartCapNone()
  347. =>    int    buffer containing drawfile
  348.  
  349. Sets no cap at the start of the path.
  350.  
  351. --------------------------------------------------------
  352.  
  353. PROCshell_DrawSetStartCapRound()
  354. =>    int    buffer containing drawfile
  355.  
  356. Sets a round cap at the start of the path.
  357.  
  358. --------------------------------------------------------
  359.  
  360. PROCshell_DrawSetStartCapSquare()
  361. =>    int    buffer containing drawfile
  362.  
  363. Sets a square cap at the start of the path.
  364.  
  365. --------------------------------------------------------
  366.  
  367. PROCshell_DrawSetStartCapTriangle()
  368. =>    int    buffer containing drawfile
  369.     int    width  of arrowhead (current units)
  370.     int    length of arrowhead (current units)
  371.  
  372. Sets a triangular cap at the start of the path.
  373.  
  374. --------------------------------------------------------
  375.  
  376. PROCshell_DrawSetEndCapNone()
  377. =>    int    buffer containing drawfile
  378.  
  379. Sets no cap at the end of the path.
  380.  
  381. --------------------------------------------------------
  382.  
  383. PROCshell_DrawSetEndCapRound()
  384. =>    int    buffer containing drawfile
  385.  
  386. Sets a round cap at the end of the path.
  387.  
  388. --------------------------------------------------------
  389.  
  390. PROCshell_DrawSetEndCapSquare()
  391. =>    int    buffer containing drawfile
  392.  
  393. Sets a square cap at the end of the path.
  394.  
  395. --------------------------------------------------------
  396.  
  397. PROCshell_DrawSetEndCapTriangle()
  398. =>    int    buffer containing drawfile
  399.     int    width  of arrowhead (current units)
  400.     int    length of arrowhead (current units)
  401.  
  402. Sets a triangular cap at the end of the path.
  403.  
  404. --------------------------------------------------------
  405.  
  406. PROCshell_DrawSetScale()
  407. =>    int    address of drawfile buffer
  408.     real    x scale
  409.     real    y scale
  410.  
  411. Each drawfile buffer created or loaded by
  412. the library routines has a scale which is
  413. contained in the pre-header. Loading or
  414. creating a new file sets the scale to 1:1.
  415.  
  416.  
  417. --------------------------------------------------------
  418.  
  419. PROCshell_DrawGetScale()
  420. =>    int    address of drawfile buffer
  421.     real    x scale (value updated)
  422.     real    y scale (value updated)
  423.  
  424. Each drawfile buffer created or loaded by
  425. the library routines has a scale which is
  426. contained in the pre-header. This routine
  427. allows the currently set scales to be read.
  428.  
  429. --------------------------------------------------------
  430.  
  431. PROCshell_DrawResizeWindow()
  432. =>    int    address of drawfile buffer
  433.     int    window handle
  434.     int    left margin (os units)
  435.     int    bottom margin (os units)
  436.     int    right margin (os units)
  437.     int    top margin (os units)
  438.  
  439. Resizes an existing window to suit the
  440. drawfile held in the specified buffer,
  441. taking account of the current scale.
  442.  
  443. --------------------------------------------------------
  444.  
  445. PROCshell_DrawScaleToWindow()
  446. =>    int    address of drawfile buffer
  447.     int    window handle
  448.     int    left margin (os units)
  449.     int    bottom margin (os units)
  450.     int    right margin (os units)
  451.     int    top margin (os units)
  452.     real    xscl (value returned)
  453.     real    yscl (value returned)
  454.  
  455. Returns the scale factors required to fit
  456. the drawfile held in the specified buffer
  457. within the given window.
  458.  
  459. --------------------------------------------------------
  460.  
  461. PROCshell_DrawPathStart()
  462. =>    int    address of drawfile buffer
  463.     real    x coord
  464.     real    y coord
  465.  
  466. Begins a new path object
  467.  
  468. --------------------------------------------------------
  469.  
  470. PROCshell_DrawPathDrawTo()
  471. =>    int    address of drawfile buffer
  472.     real    x coord
  473.     real    y coord
  474.  
  475. Adds a line segment to the current path object
  476.  
  477. --------------------------------------------------------
  478.  
  479. PROCshell_DrawPathCloseLine()
  480. =>    int    address of drawfile buffer
  481.  
  482. Closes the current path with a line and fills the
  483. path with the current fill colour
  484.  
  485. --------------------------------------------------------
  486.  
  487. PROCshell_DrawPathEnd()
  488. =>    int    address of drawfile buffer
  489.  
  490. Closes the current path with a gap and fills the
  491. path with the current fill colour
  492.  
  493. --------------------------------------------------------
  494.  
  495. PROCshell_DrawStartGroup()
  496. =>    int    address of drawfile buffer
  497.     str    name of group (less than 12 chars)
  498.          
  499. --------------------------------------------------------
  500.  
  501. PROCshell_DrawEndGroup()
  502. =>    int    address of drawfile buffer
  503.          
  504. --------------------------------------------------------
  505.  
  506. PROCshell_DrawDestroyFile()
  507. =>    int    address of drawfile buffer
  508.  
  509. Removes the definition of a DrawFile and frees the
  510. memory used.
  511.  
  512. --------------------------------------------------------
  513.  
  514. PROCshell_DrawSetPathPattern()
  515. =>    int    address of drawfile buffer
  516.     bool    TRUE for dashed lines, otherwise FALSE
  517.     real    offset
  518.     int    number of elements
  519.     real    length (current units)
  520.  
  521. Sets the current path pattern (dashed etc).
  522.  
  523. --------------------------------------------------------
  524.  
  525. PROCshell_DrawSpriteArea()
  526. =>    int    address of drawfile buffer (updated on return)
  527.     int    area size
  528.     int    address of sprite area (updated on return)
  529.  
  530. Creates a sprite area within a DrawFile buffer.
  531.  
  532. --------------------------------------------------------
  533.  
  534. PROCshell_DrawSetJoinStyleNone()
  535. =>    int    buffer containing drawfile
  536.  
  537. Sets a mitred join where two paths meet.
  538.  
  539. --------------------------------------------------------
  540.  
  541. PROCshell_DrawSetJoinStyleRound()
  542. =>    int    buffer containing drawfile
  543.  
  544. Sets a rounded join where two paths meet.
  545.  
  546. --------------------------------------------------------
  547.  
  548. PROCshell_DrawSetJoinStyleBevelled()
  549. =>    int    buffer containing drawfile
  550.  
  551. Sets a bevelled join where two paths meet.
  552.  
  553. --------------------------------------------------------
  554.